Overview
The Single API setup for impact program validation allows you to collect and submit applications for your program within your app or website and receive a single notification with the success or failure status as soon as Goodstack has reviewed the application.
If you would prefer Goodstack to host the UI for your application flow, or are limited in engineering resource, please have a look at our hosted setup.
Below we will outline a typical API implementation that our customers follow when building their impact program flow:
1. Get your API keys
Get in touch with our product & engineering team to get access to the dashboard: engineering-support@goodstack.io
Before you start your implementation, you’ll need access to the dashboard to retrieve your Goodstack API keys.
Go to the Keys page in your Partner dashboard to access your Publishable Key as well as your Secret Key.
Overview
Authenticate your API requests by using these API keys in the request header.
The secret key should be used for server to server requests and the publishable key for requests via your front end to any public API services.
Header parameter name: Authorization
Please do not publish your private key in repos or use anywhere in front end.
2. Search for organization or collect organization information
For this step, you’ll need the Search Organisations API.
Guide your users to search for their nonprofit or other good cause through your frontend application or website. You can implement this using the Search Organisations endpoint. This API can be authenticated with your publishable key, so the feature can be built entirely in your front end.
We recommend collecting the country of the applicant as a first step in your flow in order to filter search results more efficiently. You can call our Countries API to fetch available countries on demand or use static data. Our other APIs require an ISO three letter country code. e.g. FRA
Organizations can be filtered by:
→ Country using the countryCode parameter;
→ A query parameter, that searches organization name, registry ID and description, if available
→ Registry ID, such as EIN, using the registryID parameter;
→ Or other filters listed in Search Organisations endpoint.
Customers most often use a combination of countryCode and the query filter to implement search.
A: Organization exists
If the user identifies and selects their organization, you will have an organisationId field from the search result to submit with the Validation Submission request in Part 3.
B: Organization not found
If the organization search returns no results or the user can’t identify their organization, you’ll need to collect further details about your user’s org and submit them to us in the Validation Submission.
The information that we need to conduct a Validation Request in this case are:
→ organisationName - the name of the organization
→ registryName - the registry where the organization is officially registered, e.g. the Inland Revenue Service
→ registryId - the unique ID of the organization in the above registry (e.g. an EIN in the United States)
→ website - the URL of the organization’s official website
→ Documentation of the organization’s status, uploaded via the Create Validation Submission Document API.
The validation submission will also require a countryCode and language field.
You can retrieve a list of available known registry names for a given country using our Registries API in order to display a dropdown list of options in your UI. You may also submit a free text value if the registry is not listed.
3. Send validation submission
All validation checks are asynchronous and typically take from a few seconds to up to 72 hours for results to be available.
Validation configuration
The checks that are run when a validation submission is sent are defined by a Validation Configuration on your account which has a unique configurationId.
Validation Configurations are set up by our onboarding team. Contact your account manager to ensure that your configuration has been set up and that you have been provided with a configurationId.
The active configurations on your account can be retrieved from the List Validation Submission Configurations API.
Each submission may include up to four separate checks:
→ Validation Request (if the request is made with no organisationId provided)
The included checks are created automatically with each Validation Submission and their IDs will be returned in the API response. You do not need to make separate API calls to create each check.
Create Submission with organisation ID
If you have an organisationId from your search results, you can create a Validation Submission by posting the ID to the Create Validation Submission endpoint:
POST https://api.goodstack.io/v1/validation-submissions
Authorization: Secret Key
Content-Type: application/json
{
"configurationId": "configuration_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"organisationId": "organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"language": "en-US"
}
Although the configurationId field is not strictly required, if not specified the API will fall back to a default account configuration. We recommend always passing the configuration to ensure that the correct one is used.
The firstName, lastName and email fields are required if the configuration includes an Agent Verification check, but can be omitted if this check is not included.
Create Submission without organisation ID
If the user cannot find their organisation, you can submit their organisation details for validation as follows:
POST https://api.goodstack.io/v1/validation-submissions
Authorization: Secret Key
Content-Type: application/json
{
"configurationId": "configuration_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"organisationName": "organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"registryName": "Charity Registry",
"registryId": "ABC 123",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"website": "https://example.com",
"countryCode": "USA",
"language": "en-US"
}
Validation Submissions created like this will have a null value for the organisationId on creation but will be assigned one if the details are found to be valid. The ID can be retrieved from webhooks or calling the GET Validation Submission API.
Uploading documents
If the organisation is not found in search results, you will also need to collect and upload documentation of status, such as nonprofit registration.
After you have created the Validation Submission, documents can be uploaded via the Create Validation Submission Document API along with the validationSubmissionId returned by the create request.
Adding metadata to a submission
The Validation Submission API also accepts a metadata object, which can be used to attach arbitrary information to a submission and retrieve it later.
This is most commonly used to link validation submissions to internal account IDs or to record additional user-supplied information from your application form.
4. Receive and process results
To receive results, you’ll need the Webhook Subscriptions API
After creating validation submissions, you’ll to be able to process the results for each check. For that, you can subscribe to notifications by creating webhook subscriptions using the Webhook Subscriptions API, and specifying the events you want to get notifications for and the URL where you wish to receive these events.
The three events linked to Validation Submissions are:
→ validation_submission.created - this is fired as soon as you successfully post to the create API
→ validation_submission.failed - sent in the event that any of the checks in the configuration fail
→ validation_submission.succeeded - sent in the event that all of the checks in the configuration pass
Handling webhooks
Before subscribing you will need to create server-side event handlers to trigger any required actions, such as account upgrades.
In the case that a validation submission has failed status, the associated webhook will include a failureReasons object with a breakdown of the checks that failed if you wish to record this information in your system or communicate it to your users.
Verifying webhooks
You can verify that the incoming webhook notification is sent by Goodstack by the following code example (Note: the code example is for a Node/Express app).
const crypto = require('crypto')
const app = require('express')
const endpointSecret = 'sk_xxxxxxxxxxxxxxxxxxxxxxxx'
const verifySignature = (secret, payload, signature) => {
const hmac = crypto.createHmac('sha256', secret)
hmac.write(payload)
hmac.end()
return hmac.read().toString('hex') === signature
}
app.post(
'/webhook',
bodyParser.raw({ type: 'application/json' }),
(request, response) => {
const payload = request.body
const sig = request.headers['Goodstack-Signature']
if (!verifySignature(endpointSecret, payload, sig)) {
response.status(403).send()
}
// perform business logic based on event
response.status(202)
},
)
You should process webhooks as quickly as possible and return a 200 response as soon as you have verified the webhook and stored it for processing. You may wish to use a queue to store the incoming events and process asynchronously.
If the webhook handler responds too slowly, this could lead to a timeout which will mean that we retry the webhook.